home *** CD-ROM | disk | FTP | other *** search
/ Stone Design / Stone Design.iso / Stone_Friends / Wave / WavesWorld / Source / Libraries / tcl7.4b3 / doc / RegExp.3 < prev    next >
Encoding:
Text File  |  1995-02-22  |  4.8 KB  |  120 lines
  1. '\"
  2. '\" Copyright (c) 1994 The Regents of the University of California.
  3. '\" Copyright (c) 1994 Sun Microsystems, Inc.
  4. '\"
  5. '\" See the file "license.terms" for information on usage and redistribution
  6. '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  7. '\" 
  8. '\" @(#) RegExp.3 1.4 95/02/22 14:27:28
  9. '\" 
  10. .so man.macros
  11. .HS Tcl_RegExpMatch tclc 7.4
  12. .BS
  13. .SH NAME
  14. Tcl_RegExpMatch, Tcl_RegExpCompile, Tcl_RegExpExec, Tcl_RegExpRange \- Pattern matching with regular expressions
  15. .SH SYNOPSIS
  16. .nf
  17. \fB#include <tcl.h>\fR
  18. .sp
  19. int
  20. \fBTcl_RegExpMatch\fR(\fIinterp\fR, \fIstring\fR, \fIpattern\fR)
  21. .sp
  22. .VS
  23. Tcl_RegExp
  24. \fBTcl_RegExpCompile\fR(\fIinterp\fR, \fIpattern\fR)
  25. .sp
  26. int
  27. \fBTcl_RegExpExec\fR(\fIinterp\fR, \fIregexp\fR, \fIstring\fR, \fIstart\fR)
  28. .sp
  29. \fBTcl_RegExpRange\fR(\fIinterp\fR, \fIindex\fR, \fIstartPtr\fR, \fIendPtr\fR)
  30. .VE
  31. .SH ARGUMENTS
  32. .AS Tcl_Interp *interp
  33. .AP Tcl_Interp *interp in
  34. Tcl interpreter to use for error reporting.
  35. .AP char *string in
  36. String to check for a match with a regular expression.
  37. .AP char *pattern in
  38. String in the form of a regular expression pattern.
  39. .AP Tcl_RegExp regexp in
  40. .VS
  41. Compiled regular expression.  Must have been returned previously
  42. by \fBTcl_RegExpCompile\fR.
  43. .AP char *start in
  44. If \fIstring\fR is just a portion of some other string, this argument
  45. identifies the beginning of the larger string.
  46. If it isn't the same as \fIstring\fR, then no \fB^\fR matches
  47. will be allowed.
  48. .AP int index in
  49. Specifies which range is desired:  0 means the range of the entire
  50. match, 1 or greater means the range that matched a parenthesized
  51. sub-expression.
  52. .AP char **startPtr out
  53. The address of the first character in the range is stored here, or
  54. NULL if there is no such range.
  55. .AP char **endPtr out
  56. The address of the character just after the last one in the range
  57. is stored here, or NULL if there is no such range.
  58. .VE
  59. .BE
  60.  
  61. .SH DESCRIPTION
  62. .PP
  63. \fBTcl_RegExpMatch\fR determines whether its \fIpattern\fR argument
  64. matches \fIregexp\fR, where \fIregexp\fR is interpreted
  65. as a regular expression using the same rules as for the
  66. \fBregexp\fR Tcl command.
  67. If there is a match then \fBTcl_RegExpMatch\fR returns 1.
  68. If there is no match then \fBTcl_RegExpMatch\fR returns 0.
  69. If an error occurs in the matching process (e.g. \fIpattern\fR
  70. is not a valid regular expression) then \fBTcl_RegExpMatch\fR
  71. returns \-1 and leaves an error message in \fIinterp->result\fR.
  72. .PP
  73. .VS
  74. \fBTcl_RegExpCompile\fR, \fBTcl_RegExpExec\fR, and \fBTcl_RegExpRange\fR
  75. provide lower-level access to the regular expression pattern matcher.
  76. \fBTcl_RegExpCompile\fR compiles a regular expression string into
  77. the internal form used for efficient pattern matching.
  78. The return value is a token for this compiled form, which can be
  79. used in subsequent calls to \fBTcl_RegExpExec\fR or \fBTcl_RegExpRange\fR.
  80. If an error occurs while compiling the regular expression then
  81. \fBTcl_RegExpCompile\fR returns NULL and leaves an error message
  82. in \fIinterp->result\fR.
  83. .PP
  84. \fBTcl_RegExpExec\fR executes the regular expression pattern matcher.
  85. It returns 1 if \fIstring\fR contains a range of characters that
  86. match \fIregexp\fR, 0 if no match is found, and
  87. \-1 if an error occurs.
  88. In the case of an error, \fBTcl_RegExpExec\fR leaves an error
  89. message in \fIinterp->result\fR.
  90. When searching a string for multiple matches of a pattern,
  91. it is important to distinguish between the start of the original
  92. string and the start of the current search.
  93. For example, when searching for the second occurrence of a
  94. match, the \fIstring\fR argument might point to the character
  95. just after the first match;  however, it is important for the
  96. pattern matcher to know that this is not the start of the entire string,
  97. so that it doesn't allow \fB^\fR atoms in the pattern to match.
  98. The \fIstart\fR argument provides this information by pointing
  99. to the start of the overall string containing \fIstring\fR.
  100. \fIStart\fR will be less than or equal to \fIstring\fR;  if it
  101. is less than \fIstring\fR then no \fB^\fR matches will be allowed.
  102. .PP
  103. \fBTcl_RegExpRange\fR may be invoked after \fBTcl_RegExpExec\fR
  104. returns;  it provides detailed information about what ranges of
  105. the string matched what parts of the pattern.
  106. \fBTcl_RegExpRange\fR returns a pair of pointers in \fI*startPtr\fR
  107. and \fI*endPtr\fR that identify a range of characters in
  108. the source string for the most recent call to \fBTcl_RegExpExec\fR.
  109. \fIIndex\fR indicates which of several ranges is desired:
  110. if \fIindex\fR is 0, information is returned about the overall range
  111. of characters that matched the entire pattern;  otherwise,
  112. information is returned about the range of characters that matched the
  113. \fIindex\fR'th parenthesized subexpression within the pattern.
  114. If there is no range corresponding to \fIindex\fR then NULL
  115. is stored in \fI*firstPtr\fR and \fI*lastPtr\fR.
  116. .VE
  117.  
  118. .SH KEYWORDS
  119. match, pattern, regular expression, string, subexpression
  120.